Support string enums in LiquidDoc parameter types by clauderic · Pull Request #1310 · Shopify/theme-tools

clauderic · 2026-09-29T19:51:05Z

What are you adding in this PR?

LiquidDoc @param types can now be string enums:

{% doc %}
  @param {'heading' | 'small'} [variant] - Text style
{% enddoc %}

Theme Check accepts these declarations. It checks literal arguments to render (including with/for aliases), content_for and block against the allowed values, and suggests each allowed value as a replacement. When adding a missing required argument to render or content_for, it inserts the first allowed value. Dynamic values such as variables are not checked. Block parameters backed by a schema setting keep the setting's type, as in Validate block call parameters #1306.
The language server keeps the allowed values through assignments and default, shows them in hovers and completion docs, and inserts the first one in render, content_for and block parameter completions.
The parser no longer ends a LiquidDoc type at a } inside a quoted string. If a quote is left open, the type still ends at the first }, as before.

Enums are modeled as unions of string literal types rather than as a dedicated enum kind. Unions such as {string | number} or {product | collection} and discriminated unions (#223) can therefore build on this without another change to the model. For now, only string literals parse as union members.

The four commits are meant to be reviewed in order: parser fix, declarations, argument checks, language server.

What's next? Any followup issues?

General unions such as {string | number} and {product | collection}: the parser has to accept type names as union members, and the checks and type system need rules for mixed unions.
Discriminated unions: Support discriminated unions #223.
Enums on schema-backed block parameters: the setting's type wins, so an enum declared for a text or select setting is not enforced at call sites yet.

Tophatting

In a snippet snippets/text.liquid that declares the @param above:

Hover {{ variant }}: it shows 'heading' | 'small'.
Hover style after {% assign style = variant | default: 'heading' %}: it still shows 'heading' | 'small'.
In a template, {% render 'text', variant: 'body' %} is reported, with suggestions to replace 'body' with 'heading' or 'small'.

I added screenshots of the changes (before and after the changes if applicable)

Before you deploy

I included a minor bump changeset
My feature is backward compatible
I included a patch bump changeset

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>

charlespwd

.

charlespwd · 2026-09-30T18:06:51Z

+function findTypeEnd(text: string, start: number): number {
+  if (text[start] !== '{') return -1;
+
+  let quote: string | undefined;
+  let recoveryBrace = -1;
+
+  for (let pos = start + 1; pos < text.length; pos++) {
+    const ch = text[pos];
+    if (ch === '\n' || ch === '\r') break;
+
+    if (quote) {
+      if (ch === quote) {
+        if (
+          recoveryBrace !== -1 &&
+          /^[ \t]*(?:\[[^\]]*\]|[\w][\w-]*)[ \t]+/.test(text.slice(recoveryBrace + 1, pos))
+        ) {
+          let next = pos + 1;
+          while (text[next] === ' ' || text[next] === '\t') next++;
+          // An unmatched quote can close at an apostrophe in the parameter's
+          // description, which need not have a dash. A real type delimiter wins;
+          // otherwise prefer a recognizable parameter boundary, even at EOL.
+          // This also recovers ambiguous input with a missing outer brace and a
+          // parameter-looking name inside its last string literal.
+          if (text[next] !== '|' && text[next] !== '}') {
+            return recoveryBrace + 1;
+          }
+        }
+        quote = undefined;
+        recoveryBrace = -1;
+      } else if (ch === '}' && recoveryBrace === -1) {
+        recoveryBrace = pos;
+      }
+      continue;
+    }
+
+    if (ch === '}') return pos + 1;
+    // Liquid strings do not interpret backslash escapes.
+    if (ch === "'" || ch === '"') quote = ch;
+  }
+
+  // Keep a malformed, closed annotation recognizable to semantic checks, and
+  // preserve its parameter name even when a string quote is missing.
+  return recoveryBrace === -1 ? -1 : recoveryBrace + 1;
+}


Yuk. Can we not tokenize and consume tokens here instead? Why are we going ch by ch? This feels fast but also gross.

I feel like a stack based parser here would make this a bit easier to follow. I don’t like the lookback.

charlespwd · 2026-09-30T18:06:51Z

+    it('keeps the schema type of a setting that LiquidDoc declares as a string enum', async () => {
+      const block = blockSource(
+        [{ id: 'variant', type: 'text' }],
+        ["@param {'heading' | 'small'} [variant] - Variant"],
+      );
+
+      expect(await definitions(block)).toEqual([]);
+      expect(await run("{% block 'card', variant: 'body' %}{% endblock %}", block)).toEqual([]);
+    });


We’re missing a failure case?

charlespwd · 2026-09-30T18:06:51Z

+  it('preserves the existing behavior when no docset is supplied', async () => {
+    const source = `{% doc %}\n  @param {'heading' |} variant\n{% enddoc %}`;
+    const offenses = await runLiquidCheck(ValidDocParamTypes, source, undefined, {
+      themeDocset: undefined,
+    });
+    expect(offenses).toHaveLength(0);
+  });


Shouldn’t that be an error?

charlespwd · 2026-09-30T18:06:51Z

+                let start = node.paramType.position.start - 1;
+                let end = node.paramType.position.end + 1;
+                while (/[ \t]/.test(node.source.charAt(start - 1))) start--;
+                while (/[ \t]/.test(node.source.charAt(end))) end++;


charlespwd · 2026-09-30T18:06:51Z

+      const compatibility = isArgumentTypeCompatible(expectedType, argument);
+      if (compatibility === true) return;
+
+      if (compatibility === undefined) {
+        // Aliases also check named Liquid types and arrays. Validate the
+        // declaration first so malformed types do not cause a second error.
+        if (!context.themeDocset) return;
+        validParamTypesPromise ??= context.themeDocset
+          .liquidDrops()
+          .then((entries) => new Set(getValidParamTypes(entries).keys()));
+        if (!parseParamType(await validParamTypesPromise, expectedType)) return;
      }
+


Compatibility flipping on undefined is weird. What? Weird type design

charlespwd · 2026-09-30T18:06:52Z

  kind: NodeTypes.LiquidVariable;
  node: LiquidVariable;
  offset: number;
+  resolvedType?: InferredType;


why is htis here?

charlespwd · 2026-09-30T18:07:35Z

packages/theme-check-common/src/checks/valid-render-snippet-argument-types/index.ts:18

Should doc be updated since this is also in blocks now?

charlespwd · 2026-09-30T18:21:04Z

(my diffnotes) those are meant for my agent oops

clauderic requested a review from a team as a code owner September 29, 2026 19:51

clauderic force-pushed the liquiddoc-string-literal-unions branch from b24a75f to c038b0f Compare September 29, 2026 20:31

clauderic requested a review from charlespwd September 29, 2026 20:45

clauderic and others added 4 commits September 30, 2026 11:54

Fix quoted delimiters in LiquidDoc parameter types

11fa47f

Accept string enums in LiquidDoc parameter types

295bed8

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>

Validate arguments against LiquidDoc string enums

7c8b9d4

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>

Support LiquidDoc string enums in the language server

78895cd

Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>

clauderic force-pushed the liquiddoc-string-literal-unions branch from c038b0f to 78895cd Compare September 30, 2026 15:59

charlespwd reviewed Sep 30, 2026

View reviewed changes

charlespwd mentioned this pull request Sep 30, 2026

Support string enums in LiquidDoc parameter types #1315

Merged

Navigation Menu

Support string enums in LiquidDoc parameter types - #1310

Support string enums in LiquidDoc parameter types#1310
clauderic wants to merge 4 commits into
mainfrom
liquiddoc-string-literal-unions

clauderic commented Sep 29, 2026 •

edited

Loading

Uh oh!

charlespwd left a comment •

edited

Loading

Uh oh!

charlespwd Sep 30, 2026

Uh oh!

charlespwd Sep 30, 2026

Uh oh!

charlespwd Sep 30, 2026

Uh oh!

charlespwd Sep 30, 2026

Uh oh!

charlespwd Sep 30, 2026

Uh oh!

charlespwd Sep 30, 2026

Uh oh!

charlespwd commented Sep 30, 2026

Uh oh!

charlespwd commented Sep 30, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

clauderic commented Sep 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What are you adding in this PR?

What's next? Any followup issues?

Tophatting

Before you deploy

Uh oh!

charlespwd left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

charlespwd Sep 30, 2026

Choose a reason for hiding this comment

Uh oh!

charlespwd Sep 30, 2026

Choose a reason for hiding this comment

Uh oh!

charlespwd Sep 30, 2026

Choose a reason for hiding this comment

Uh oh!

charlespwd Sep 30, 2026

Choose a reason for hiding this comment

Uh oh!

charlespwd Sep 30, 2026

Choose a reason for hiding this comment

Uh oh!

charlespwd Sep 30, 2026

Choose a reason for hiding this comment

Uh oh!

charlespwd commented Sep 30, 2026

Uh oh!

charlespwd commented Sep 30, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

clauderic commented Sep 29, 2026 •

edited

Loading

charlespwd left a comment •

edited

Loading